Roller

	This plug-in is written in Python 2.7 for GIMP v2.10. Roller is designed to create image compositions like wallpaper, image boards, collages, etc. Roller 1 through 3 presets are incompatible with Roller 4.

Basics

	Steps

	Roller breaks a render into steps. Steps are how an option group produces layer output and a step layer group. Global, Gradient Light, Backdrop are examples of an option group, each having a step. Some steps have a sub-step. A sub-step will produce an additional layer in the step's layer group.

    A View Button
    
    A view button when activated causes steps to be processed. There are two basic view types: Plan and a work-in-progress (work). For each basic view, there are two process options, a partial and a complete view. For planning, draft produces a partial plan. A partial view ends its output on the option group visible in the main window. When working, the Peek option is the partial option, while an activated Preview makes a complete view.

	Composition

	Roller creates layers like a pancake robot in a sci-fi movie, but the Backdrop Image layer and the Gradient Light output deserve a mention.

	Every composition has a Backdrop Image layer. This layer serves as a backdrop for the composition and may provide material for a Backdrop Style. Many Backdrop Styles depends on the alpha in the Backdrop Image layer. The style's tool-tip will indicate this dependency.

	Gradient Light is a gradient that is used in multiple parts of a render. It's purpose is to simulate a light source or an environment, but it has other uses, such as unifying a composition.

Model

	Each model offers unique possibilities for composing. Roller 4 has four models: Table, Cell, Stack and Box. Models share some common characteristics. They all have a Property option group and a Cell branch with a Cell Type.

    After creating a model, steps need to be added to the navigation tree in order to produce layer output. Select the Model Step button in the Model group to choose steps.

	Table
	
	The Table model has two branches: Canvas and Cell. The Canvas branch has options for modifying the canvas rectangle. The Cell branch is very much like the Canvas branch, except for the options apply to a cell rectangle.

	Table divides the canvas into a grid defined by row and column counts. Row and column intersections form a cell. The main window options apply to the entire grid. If a single cell needs to modified, the Per Cell option can be used.

	The Per Cell option when selected provides access to a cell table layout which in turn opens a Cell Editor. The Cell Type Per Cell option however only has a merge cell layout.

	Cell
	
	The Cell model has one branch: Cell. A Rectangle option defines a single cell rectangle for its output.

	Stack
	
	A Stack model has one branch, and like Cell, uses a Rectangle option to define its first cell. When Stack has more than one cell, the Add Offset X and Add Offset Y options modify the additional cell rectangle positions. For each cell after the first, the offsets are added to the previous cell rectangle's position to determine the next cell's top-left position.

	Box
	
	The Box model has three branches: Canvas, Cell, and Face. The Box grid is the same grid as the Table's hexagon-shaped cell. It's a double-spaced grid where every other cell is valid. A Face option group applies itself to each of the three faces on the Box.

	Pyramid

	A Pyramid model has two branches, Canvas and Cell. A cell is assigned with a row and its column count. The row divides its span by the column count to define the cell width. The cell height is calculated from the total number of row and the canvas space. The wide end of the Pyramid is the row one location. If the Pyramid is facing up, then row one is at the bottom. If the Pyramid is facing down, row one is at the top of the Pyramid render.

	Sidewalk

	A Pyramid model has three branches, Canvas, Cell, and Facing. Cells are arranged in a rectangular ring. The The Facing output is placed either inward or outward from the center of the cell ring. Cells on a side have perpendicular placed output, while the corner cells output direction is determined by the shape of the cell ring.

Model Step

	Before Roller processes an output request, a viewing, a list of Model Steps are created. Model Steps are option groups visible in the user interface. The steps are processed from the top-down and left-to-right as reflected in the navigation tree. Output processing starts at the bottom of the layer order and ends at the top which is the inverse of the navigation tree.

	Model Steps have three different states: excluded, available, and shelved. A Model Step's life management is set from the Model/New/Define Model dialog or the Model/Revise dialog. Available Model Steps are visible in the user interface. A Model Step can be shelved using the Model Step dialog. A shelved Model Step retains its option values between sessions while an excluded Model Step does not.

Insight

	Steps Preset
	
	This option group is found on the trunk of the navigation tree. It's positioned at the bottom of the branch list. Its value is all the available and shelved Model Step in the current Roller window. When the Roller plug-in starts it seeks and loads a "Last Used" Steps Preset. Saving a Last Used Steps Preset during a session run is advisable if you want the settings to load on your next run. Keep it mind that Roller writes this file on an Accept command from its main window.

	Cell Rectangle

	Every cell has a rectangle that defines a cell bounds. A cell's shape its determined by this limitation. However, there are other rectangles that effect how the final cell output, such as, the Shift and Margin options.

	Shift

	The Shift options adjust a rectangle's size and position. There are Canvas and Cell versions of Shift. The Cell version may have a Per Cell option which can change a single cell's rectangle.
	
	Margin

	Margin options apply inside a cell rectangle. They produce a pocket rectangle. An Image option group is always limited to the pocket, but other option groups have an Obey Margins options which, when off, causes the output to ignore the pocket limitation.

	Cell Shape
		
	A cell shape has two variations. The cell rectangle defines the original shape of the cell. If margins apply, then there is an additional cell shape created. Option groups will use one or the other cell shape when masking and sizing layer output.

	Image Mould

	The image Mould process ensures that an image fits inside a pocket. If an image is larger than its pocket, the image may be scaled down depending on the Resize Method. On the other hand, depending on the Resize Method and image justification, an image may be enlarged in order to fill a pocket.

Adding Frames to the Frame Folder
		
	During start-up, Roller compiles a list of '.png' file types from Roller's Frame folder. You can add additional frames to this folder. In order to add your own frames, they must be the '.png' file type. The frames are used solely by the Frame/Frame Over option. Gratitude to dinasset from 'gimpchat.com' for sharing the frame files.

Errors And Limitations To Be Aware Of

	* If an image is referenced from a File or Folder image source is displaying black instead of image material, try converting the image to GIMP's sRGB color profile prior to running Roller.

	* There's a problem with the Color Picker dialog that is provided by the outdated GTK 2.0. There's an Entry widget next to the opacity slider that doesn't actually modify the opacity setting. The opacity slider works as advertised though.

	* Opening and closing images in GIMP while Roller is open may make Roller unstable.

	* Putting too many rows and columns into a composition grid may result in a crash. GTK has its limitations, and Roller doesn't compensate for a grossly large scale. The Merge Cells window may come to a crawl when drawing a multitude of cells. I was able to create a grid of 15 rows and 15 columns without too much of a delay. So patience may be in order if you wish to create a larger grid of cells.

	* I recommend having the Layer Dock visible while running Roller as this dock will show GIMP working.

	* Roller doesn't save images. Only Preset files in Roller Preset folder are saved.

	* Two running Roller scripts will likely crash into each other.

	* When the script is run for the first time, Python creates ".pyc" type files within the Module folder. These files help the code run faster in the Python interpreter. The files are re-created if they go missing, so no worries about deleting them.

      * Some dynamic brushes, when applied as brush stroke, may not work with Brush Punch and and Fringe. I have no idea why. If you know, please let me know.

	* Roller uses the clipboard to make image snapshots. If there is another background process also using the clipboard, then this can cause the copy and paste operation to fail resulting in a completely black output.

	* Testing and designing a composition can be sped up in several ways.
		1) Reduce the size of the render.
		2) Turn off unused option groups.
		3) Move steps to the model list shelf.
		4) Be mindful of the background update layers:
		   Average Color, Backdrop, and Blur Behind.

	* It's safe to adjust layer opacity and mode in the Layer Dock while Roller is idle. However, Roller won't see these kind of changes during its processing.

Special Thanks

	Many thanks to the free programs Notepad++ (for easy editing), Visual Studio Code (for syntax checking), and PyCharm (for detailed code analysis). Each is a great Python code editor. Also, I would like to give a special thanks to every GIMP plug-in author for sharing their inspirational work.

	- Charles Bartley
	November 23, 2023
